This document demonstrates how to implement and plot different chart types using gevitR. This document assumes that you have already run the “Getting started with gevitR” and that the necessary data as already been loaded into your R workspace.

devtools::load_all() #temporary once things are done
library(dplyr)
library(shiny)

#Table data
tab_dat<-input_data(file = system.file("extdata", "ebov_metadata.csv", package = "mincombinr"),dataType = "table")

#Tree data
tree_dat<-input_data(file = system.file("extdata", "ebov_tree.nwk", package = "mincombinr"),dataType = "tree")

#Genomic data
genomic_dat<-input_data(file = system.file("extdata", "ebov_GIN_genomic_FIXED.fasta", package = "mincombinr"),dataType = "dna")

#Shape files
#Shape files require that .shp,.shx,and .prj files at a minimun to be in the same directory
#to add metadata to the shape file, you can also add .dbf files
gin_shape_dat<-input_data(file = system.file("extdata", "gin_admbnda_adm1_ocha_itos.shp", package = "mincombinr"),dataType = "spatial")
lbr_shape_dat<-input_data(file = system.file("extdata", "lbr_admbnda_adm1_ocha.shp", package = "mincombinr"),dataType = "spatial")
sle_shape_dat<-input_data(file = system.file("extdata", "sle_admbnda_adm1_1m_gov_ocha_20161017.shp", package = "mincombinr"),dataType = "spatial")

#put all the individual shape files together so that the system
#knows to try visualize it all together
shape_dat<-join_spatial_data(gin_shape_dat,lbr_shape_dat,sle_shape_dat)

Common statistical charts

#
# "swarmplot" => implemented specs for this

#a bar chart of all the countries invovled in the ebola outbreak
bar_chart<-specify_base(chart_type = "bar",data="tab_dat",x = "country")
plot(bar_chart)

scatter_chart<-specify_base(chart_type = "scatter",data="tab_dat",x = "latitude",y="longitude",title = "Ebola Scatter Plot")
plot(scatter_chart)

histogram_chart<-specify_base(chart_type = "histogram",data="tab_dat",x = "latitude")
plot(histogram_chart)

pdf_chart<-specify_base(chart_type = "pdf",data="tab_dat",x = "latitude")
plot(pdf_chart)

#works but weird a bit
boxplot_chart<-specify_base(chart_type = "boxplot",data="tab_dat",x = "latitude",y="country")
plot(boxplot_chart)

#we'll even let you make a pie chart
pie_chart<-specify_base(chart_type = "pie",data="tab_dat",x = "country")
plot(pie_chart)

gevitR can also work with data frames too, so you can perform some analyses and go ahead and plot the data. Here’s an example using a line chart :

#lets use our tabular data
ebov<-tab_dat@data[[1]] #make this nicer
ebov_case_counts<-ebov %>% 
  group_by(country,month) %>%
  count()

line_chart<-specify_base(chart_type = "line",data="ebov_case_counts",x = "month",y="n",group = "country")
plot(line_chart)

Colour charts

Colour charts are common statistical charts those that fundamentally require colour to communicate communicate their results. By comparsion, adding colour to a common statistical chart can be seen as an enhancements (a nice to have, not a need to have).

# "category stripe" = do.call(render_category_stripe,args = spec_list),

ebov<-tab_dat@data[[1]] #make this nicer
ebov_heat_data<-ebov %>% 
  group_by(country,month) %>%
  count()

heatmap_chart<-specify_base(chart_type = "heatmap",data="ebov_heat_data",x = "country",y="month",z = "n")
plot(heatmap_chart)

density_chart<-specify_base(chart_type = "density",data="tab_dat",x = "latitude",y="longitude")
plot(density_chart)

Category stripes are not really meant to be stand alone chart types, they are generally meant to be enhancements, typically for phylogenetic trees, where adding a category stripe is a common paradigm. But it’s possible to generate a category stripe on its own.

#this doesn't quite work when there are a lot of labels
#maybe the answer here is just a 1D tile plot..
cat_stripe_chart<-specify_base(chart_type = "category stripe",data="tab_dat",x = "site.id",y="bob",category="country")
plot(cat_stripe_chart)

Relational charts

Spatial charts

There are two ways to view a geographic map. First, working from shape files:

First, there’s everything together

spatial_chart<-specify_base(chart_type="choropleth",data="shape_dat")
plot(spatial_chart)

Also, it possible just to see one individual map too, not just everything together

spatial_chart<-specify_base(chart_type="choropleth",data="gin_shape_dat")
plot(spatial_chart)

Second, is working from a co-ordinates from a tabular data file. The background raster image is supplied by the ‘Openstreemaps’ package (and the broader project). They do great work, consider supporting them if you like this feature too.

map_chart<-specify_base("geographic map",data="tab_dat",lat = "latitude",long = "longitude")
plot(map_chart)

Tree charts

phyloTree_chart<-specify_base(chart_type = "phylogenetic tree",data="tree_dat")
plot(phyloTree_chart)

Genomic charts

A very standard alignment chart. This tends to still work if you’ve got very long sequences. There are some options to simply the output too. It’s possible to pass a diff_only parameter, which will only show variant positions.

genome_chart<-specify_base(data = "genomic_dat",chart_type = "alignment")
plot(genome_chart)

Sequence logo plots are also supported. These work well when there are a small number of variant positions, but when there are many, it’s actually not a very nice visual. The user will recieve a prompt in those circumstances.

seqlogo_chart<-specify_base(data = "genomic_dat",chart_type = "sequence logo")
plot(seqlogo_chart)
## Warning in (function (...) : These are long sequences! The sequence
## logo plot generally doesn't look. I'll display it, but consider using an
## alignment instead.

See? Too many. Instead, it might be better to select a few specific regions to show that the user might know about. In the first case, there will be a warning the nothing is very different and the plot won’t show:

seqlogo_chart<-specify_base(data = "genomic_dat",chart_type = "sequence logo",show_pos = 1:20)
plot(seqlogo_chart)
## Warning in (function (...) : These are long sequences! The sequence
## logo plot generally doesn't look. I'll display it, but consider using an
## alignment instead.

But there is a slightly more clever way to go about this too:

diff_seq<-get_diff_pos(genomic_dat) #little helper function that extracts the similar sequences
seqlogo_chart<-specify_base(data = "genomic_dat",chart_type = "sequence logo",show_pos = diff_seq[1:20])
plot(seqlogo_chart)

Temporal charts

Sometimes data contains start and end dates and its desireable to show these as different types of temporal charts. There are two times of timelines that can be created. One is a “gant chart” type timeline that will show both ranges and single events. Another is the standard epidemic curve, which is essentially a very special case of a histogram or bar chart, depending upon the user.

#using the existing tabular data
tmp<-tab_dat@data[[1]]
tmp$collection_date<-as.Date(tmp$collection_date)

#let's add some end dates to keep it interesting
tmp$collection_date_end<-tmp$collection_date + sample(10:30,nrow(tmp),replace = TRUE)

tmp$collection_date_end<-sapply(as.character(tmp$collection_date_end),function(x){
   if(runif(1)>0.9)
     return(x)
    return(NA)
})

timeline_chart<-specify_base(chart_type = "timeline",data="tmp",start = "collection_date", end ="collection_date_end", y = "site.id")
plot(timeline_chart)
## Warning in (function (...) : End date is not a date class. Will try to
## automatically convert it - unintended side effects may occur.
## Warning: Ignoring unknown aesthetics: xend, yend

Since there’s a lot going on because there are a lot of different things here, let’s subset this to get a better view of what is going on. So here, only plotting those items that are ranges.

tmp_sub<-dplyr::filter(tmp,!is.na(collection_date_end))

timeline_chart<-specify_base(chart_type = "timeline",data="tmp_sub",start = "collection_date", end ="collection_date_end", y = "site.id",color = "country")
plot(timeline_chart)
## Warning in (function (...) : End date is not a date class. Will try to
## automatically convert it - unintended side effects may occur.
## Warning: Ignoring unknown aesthetics: xend, yend

Images

Sometimes it is desireable to use image data, these can be from interior maps or from gel images. Getting image data to work is a little bit more invovled because it requires there be some annotation data that allows you to link pixel space to something useful. There’s a small application embedded withing this package that lets you do that.

Here’s a workflow with a few different types of images

interior_img<-input_data(file = system.file("extdata", "random_interior_map.tiff", package = "mincombinr"),dataType = "image")
## Warning in input_image(file, asObj, dataID, desc, ...): To use this
## image, please be sure to have separate file that links the image to data
## in pixel space. If you would like to CREATE an annotation file, run the
## 'annotate_image' command.

It’s still possible to simply draw a plot that has no metadata

img_chart<-specify_base(chart_type="image",data="interior_img")
plot(img_chart)

But it’s nice to do something more useful with a picture, so… the error is to remind the user that there needs to be some image file loaded. So, now we’ll run the special app. Note that in building this markdown file, this particular line of code is not run:

interior_img<-annotate_image(interior_img)

#the annotations are automatically there now:
metadata<-interior_img@data$metadata

save(file="../inst/extdata/img_meta.rds",metadata)
#We'll load an already annotated image to keep things going
#Normally, the user doesn't do this, but we have to do so because
#the previous line of code was not run in the markdown notebook
load(file = system.file("extdata", "img_meta.rds", package = "mincombinr"))
interior_img@data$metadata<-metadata

#let's state the spec of the interior map
img_chart<-specify_base(chart_type="image",data="interior_img")
plot(img_chart)

Now, let’s do something more interesting, let’s colour these regions

#Finally, lets add some arbitrary case counts to the room
interior_img@data$metadata$counts<-c(100,35)

#let's state the spec of the interior map
img_chart<-specify_base(chart_type="image",data="interior_img",color = "counts")
plot(img_chart)

The other most common type of image is a gel image - this too can now be part of the analysis fun.

gel_img<-input_data(file = system.file("extdata", "gel_image.tiff", package = "mincombinr"),dataType = "image")
## Warning in input_image(file, asObj, dataID, desc, ...): To use this
## image, please be sure to have separate file that links the image to data
## in pixel space. If you would like to CREATE an annotation file, run the
## 'annotate_image' command.
gel_img_chart<-specify_base(chart_type="image",data="gel_img")
plot(gel_img_chart)

#Not run in notebook image script but once again, annotate the image
gel_img<-annotate_image(gel_img)
metadata<-gel_img@data$metadata
metadata$element_name<-paste("item",1:nrow(metadata),sep="_")

save(metadata,file="../inst/extdata/gel_img_meta.rds")
load(file = system.file("extdata", "gel_img_meta_shipped.rds", package = "mincombinr"))
gel_img@data$metadata<-metadata

gel_img@data$metadata$rnd_class<-sample(c("Resistant","Susceptible"),replace = TRUE,size=nrow(metadata))

gel_chart<-specify_base(data="gel_img",chart_type = "image",color="rnd_class")
plot(gel_chart)